[アップデート] Amazon Connectで音声プロンプトの操作をAPI (AWS CLI、CloudFormation等) を使って行えるようになりました

みなさん、こんにちは！
福岡オフィスの青柳です。

Amazon Connectの「音声プロンプト」の作成や削除などの操作に関して、これまでGUI (Amazon Connectコンソール) からのみ行えていましたが、新たにAPIを使って行えるようになりました。

Amazon Connect launches APIs to programmatically configure prompts

「APIを使って行える」と言われてもピンと来ないかもしれませんが、APIに対応したことにより「AWS CLI」や「AWS CloudFormation」を使って音声プロンプトを作成できるようになった、というアップデートになります。

「音声プロンプト」とは？

まず最初に、今回のアップデートの対象となる「音声プロンプト」について確認しておきます。
(「音声プロンプト」は、単に「プロンプト」とも呼ばれます。)

コンタクトフローの中で「プロンプトの再生」ブロックを使うことで、電話を掛けてきた顧客に対して音声による自動アナウンスを行うことができます。

この時、再生する「(広義の) プロンプト」を指定する方法として、以下の3通りの方法が用意されています。

• (1) 「プロンプトライブラリ」に予め登録しておいた音声ファイルを再生する
• (2) S3バケットに配置した音声ファイルを再生する
• (3) テキストの内容を「Amazon Polly」の音声合成を使って読み上げる

今回のアップデートの対象となるのは、これらのうちの (1) です。

つまり、Amazon Connectコンソールの「音声プロンプトの管理」で管理されている音声プロンプトの「作成」や「削除」などの操作をAPI (AWS CLI、CloudFormation) を使って行えるようになったということです。

AWS CLIを使って音声プロンプトを操作する

それではまず、AWS CLIを使って音声プロンプトの操作を行ってみます。

前提条件として、AWS CLIのバージョンが下記を満たしている必要があります。

• AWS CLI v2系： バージョン 2.11.21 以降
• AWS CLI v1系： バージョン 1.27.136 以降

list-prompts (音声プロンプトの一覧を表示する)

最初に、プロンプトライブラリに登録されている音声プロンプトの一覧を表示する「list-prompts」コマンドを使ってみます。

$ aws connect list-prompts --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

必須のパラメーターは--instance-id(Amazon ConnectインスタンスID) のみです。

実行すると、以下のように結果が返ってきます。

{
    "PromptSummaryList": [
        {
            "Id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "Arn": "arn:aws:connect:ap-northeast-1:123456789012:instance/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/prompt/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "Name": "Beep.wav"
        },
        {
            "Id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "Arn": "arn:aws:connect:ap-northeast-1:123456789012:instance/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/prompt/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "Name": "CustomerHold.wav"
        },

・・・(中略)・・・

    ]
}

AWS CLI共通のパラメーターを利用することで、例えば--outputで出力形式を指定したり、--queryで出力結果を加工することができます。

実行例を以下に示します。

$ aws connect list-prompts \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --query "sort_by(PromptSummaryList[].{Name:Name,Id:Id},&Name)" \
    --output table

-----------------------------------------------------------------------------------------
|                                      ListPrompts                                      |
+---------------------------------------+-----------------------------------------------+
|                  Id                   |                     Name                      |
+---------------------------------------+-----------------------------------------------+
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  Beep.wav                                     |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  CustomerHold.wav                             |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  CustomerQueue.wav                            |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  Music_Jazz_MyTimetoFly_Inst.wav              |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  Music_Pop_ThisAndThatIsLife_Inst.wav         |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  Music_Pop_ThrowYourselfInFrontOfIt_Inst.wav  |
|  XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |  Music_Rock_EverywhereTheSunShines_Inst.wav   |
+---------------------------------------+-----------------------------------------------+

create-prompt (音声プロンプトをS3バケットから新規登録する)

次に、音声プロンプトを新規登録する「create-prompt」コマンドを使ってみます。

create-promptコマンドを実行する際には、登録する音声プロンプトの基となる「音声ファイル」を予めS3バケットに配置しておく必要があります。

$ aws connect create-prompt \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --s3-uri s3://<S3 Bucket Name>/sample_audio_file.wav \
    --name sample_prompt \
    --description "Sample Prompt" \
    --tags "System=example,Environment=prod"

以下のパラメーターを指定します。(★は必須のパラメーターです)

• --instance-id： Amazon ConnectインスタンスID ★
• --s3-uri： 音声ファイルのS3パス (「s3://バケット名/オブジェクト名」形式) ★
• --name： プロンプトの表示名 ★
• --description： プロンプトの説明 (省略可)
• --tags： リソースタグ (省略可)

「プロンプトの説明」と「リソースタグ」は、Amazon Connectコンソールの「音声プロンプトの管理」画面には表示されませんが、後述する「desctibe-prompt」コマンドを使って参照することができます。

コマンドを実行すると、以下のように結果が表示されます。
(登録した音声プロンプトの「ARN」と「ID」を確認することができます)

{
    "PromptARN": "arn:aws:connect:ap-northeast-1:123456789012:instance/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/prompt/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "PromptId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

(留意事項) 登録する音声ファイルのフォーマットについて

Amazon Connectの音声プロンプトでは「サポートする音声ファイルの仕様」が定められています。

Amazon Connectが内部で管理する「音声プロンプト」の仕様では、「コーデック：μ-law形式」「サンプリング周波数：8kHz」「量子化ビット数：8bit」というように、厳密にフォーマットが決まっています。

ただし、Amazon Connectコンソールの「音声プロンプトの管理」画面から音声ファイルを登録する際は、一般的な「wav」形式 (PCM形式) の音声ファイルでも登録することができます。 (登録する際にAmazon Connectが自動的にフォーマットを変換します)

では、API (AWS CLI) を使って音声プロンプトを登録する場合は、音声ファイルのフォーマットはどのようにするべきなのでしょうか？

検証したところ、「音声プロンプトの管理」画面から登録する際と同様に、一般的な「wav」形式 (PCM形式) の音声ファイルを用いることができました。

しかし、上記のブログ記事でも案内している通り、可能であればAmazon Connectが内部で管理する「μ-law」形式の音声ファイルを用意することを推奨します。 (自動変換による音質劣化の可能性を回避することができるため)

describe-prompt (音声プロンプトの情報を表示する)

コマンドの解説に戻りましょう。

音声プロンプトの情報を表示する「describe-prompt」コマンドを使ってみます。

$ aws connect describe-prompt \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --prompt-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

以下のパラメーターを指定します。(★は必須のパラメーターです)

• --instance-id： Amazon ConnectインスタンスID ★
• --prompt-id： プロンプトID ★

実行すると、以下のように結果が返ってきます。
(create-promptコマンド実行時に「プロンプトの説明」と「リソースタグ」を指定した場合は、このように表示されます)

{
    "Prompt": {
        "PromptARN": "arn:aws:connect:ap-northeast-1:123456789012:instance/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/prompt/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "PromptId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "Name": "sample_prompt",
        "Description": "Sample Prompt",
        "Tags": {
            "Environment": "prod",
            "System": "example"
        }
    }
}

get-prompt-file (音声プロンプトをファイルに抽出する)

次に、音声プロンプトをファイルに抽出する「get-prompt-file」コマンドを使ってみます。

このコマンドを実行すると、直接ファイルをダウンロードできたり、指定したS3バケットに音声ファイルを書き出したりできる訳ではなく、音声ファイルをS3の「署名付きURL」として取得することができます。

$ aws connect get-prompt-file \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --prompt-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

以下のパラメーターを指定します。(★は必須のパラメーターです)

• --instance-id： Amazon ConnectインスタンスID ★
• --prompt-id： プロンプトID ★

実行すると、以下のように結果が返ってきます。

{
    "PromptPresignedUrl": "https://amazon-connect-prompts-nrt-prod-cell-1.s3.ap-northeast-1.amazonaws.com/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.wav?X-Amz-Security-Token=...."
}

「PromptPresignedUrl」に表示されているURLにアクセスすると、Webブラウザの種類によっては直ちにダウンロードが始まったり、メニューから「ダウンロード」操作を行うことでダウンロードが始まります。

なお、結果として返ってくるURLは「署名付きURL」ですので、特定のアクセス権限は必要とせず、URLを知っていれば誰でもアクセスできることに留意してください。

ちなみに、署名付きURLに含まれるX-Amz-Expires=60という記述から、URLの有効期限は「60秒 (1分)」であると思われます。 (この有効期限を変更する方法は無いようです)

update-prompt (音声プロンプトを更新する)

次に、音声プロンプトを更新する「update-prompt」コマンドを使ってみます。

$ aws connect update-prompt \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --prompt-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --s3-uri s3://<S3 Bucket Name>/another_sample_audio_file.wav \
    --name sample_prompt_2 \
    --description "Sample Prompt #2"

以下のパラメーターを指定します。(★は必須のパラメーターです)

• --instance-id： Amazon ConnectインスタンスID ★
• --prompt-id： プロンプトID ★
• --s3-uri： 音声ファイルのS3パス (「s3://バケット名/オブジェクト名」形式) (省略可)
• --name： プロンプトの表示名 (省略可)
• --description： プロンプトの説明 (省略可)

--s3-uri、--name、--descriptionは、いずれか最低1つは指定する必要がありますが、全てを指定する必要はなく、変更したい要素のみ指定することが可能です。

コマンドを実行すると、以下のように結果が表示されます。

{
    "PromptARN": "arn:aws:connect:ap-northeast-1:123456789012:instance/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/prompt/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "PromptId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

delete-prompt (音声プロンプトを削除する)

最後に、音声プロンプトを削除する「delete-prompt」コマンドを使ってみます。

$ aws connect delete-prompt \
    --instance-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX \
    --prompt-id XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

以下のパラメーターを指定します。(★は必須のパラメーターです)

• --instance-id： Amazon ConnectインスタンスID ★
• --prompt-id： プロンプトID ★

実行しても結果は何も表示されません。

これで、AWS CLIを使った一連の「音声プロンプトの操作方法」の解説が終わりました。

CloudFormationを使って音声プロンプトを作成する

今度はCloudFormationを使って音声プロンプトの作成を自動化してみましょう。

今回のアップデートにより、CloudFormationに新たなリソース「AWS::Connect::Prompt」が追加されています。

リソース記述のフォーマットは以下のようになっています。

Type: AWS::Connect::Prompt
Properties:
  InstanceArn: Amazon ConnectインスタンスARN (必須)
  S3Uri: 音声ファイルのS3パス (「s3://バケット名/オブジェクト名」形式) (必須)
  Name: プロンプトの表示名 (必須)
  Description: プロンプトの説明 (省略可)
  Tags: (省略可)
    - タグキー・タグ値のセット

実際のテンプレートの記述例を以下に示します。

---
AWSTemplateFormatVersion: "2010-09-09"
Description: "Amazon Connect Prompts Example"

Resources:
  ConnectInstance:
    Type: AWS::Connect::Instance
    Properties:
      InstanceAlias: "example-connect-instance"
      IdentityManagementType: CONNECT_MANAGED
      Attributes:
        InboundCalls: true
        OutboundCalls: true

  ConnectPrompt:
    Type: AWS::Connect::Prompt
    Properties:
      InstanceArn: !Ref ConnectInstance
      S3Uri: "s3://<S3 Bucket Name>/sample_audio_file.wav"
      Name: "sample_prompt"
      Description: "Sample Prompt"
      Tags:
        - Key: System
          Value: "example"
        - Key: Environment
          Value: "prod"

このテンプレートを使ってCloudFormationスタックを作成することにより、Amazon Connectインスタンスが新規作成され、続いて音声プロンプトがS3バケット上の音声ファイルを使って登録されます。

CloudFormationですので、スタックの更新にも対応しています。

テンプレート中の「S3Uri」「Name」「Description」および「Tags」の記述内容を修正してスタックの「更新」を行うことで、実際の音声プロンプトの内容が変化することを確認してみてください。

おわりに

今回のアップデート「Amazon Connectの音声プロンプトの操作をAPIを使って行えるようになりました」を受けて、具体的に「AWS CLI」と「AWS CloudFormation」を使って音声プロンプトの操作を行う方法を解説しました。

他にも、「AWS CDK」「Terraform」などCloudFormation以外のIaCツールや、各プログラム言語向けの「AWS SDK」についても、順次対応するものと思われます。(既に対応しているものもあるでしょう)

これまでGUIを使わなければ行えなかった音声プロンプトの操作がAPIを使って行えるようになったことで、管理・運用の幅が広がるのではないかと思います。